@opentelemetry/core

What is @opentelemetry/core?

The @opentelemetry/core package is part of the OpenTelemetry project, which provides a set of APIs, libraries, agents, and instrumentation to provide observability for applications. Specifically, the core package includes fundamental building blocks for creating and managing telemetry data (metrics, traces, logs) and is designed to be used by other OpenTelemetry packages to create a complete observability framework.

What are @opentelemetry/core's main functionalities?

Context Management

This feature allows for the propagation of context information across asynchronous operations in your application. The context is used to store and access current execution-specific data, such as active span in tracing.

const { context, ROOT_CONTEXT } = require('@opentelemetry/core');
const ctx = context.active();
const newContext = context.with(ROOT_CONTEXT, () => {});

Propagation

Propagation is used to transmit context (e.g., traces and correlations) across process boundaries. It includes utilities to inject and extract context information from carriers in various formats.

const { propagation, defaultTextMapGetter } = require('@opentelemetry/core');
const carrier = {};
const context = propagation.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);

Instrumentation

Instrumentation is a core part of OpenTelemetry, allowing developers to collect telemetry data (metrics, logs, and traces) from their applications. This feature provides diagnostic logging capabilities.

const { diag } = require('@opentelemetry/core');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

Other packages similar to @opentelemetry/core

jaeger-client

Jaeger client is a distributed tracing system. It's similar to @opentelemetry/core in that it provides tracing capabilities, but it's specifically designed for use with the Jaeger backend. Unlike OpenTelemetry, which aims to be vendor-neutral, Jaeger client is tailored for Jaeger.

prom-client

Prom-client is a client for the Prometheus monitoring system, focusing on gathering metrics. It's similar to the metrics collection part of @opentelemetry/core but is specifically designed for use with Prometheus rather than being part of a broader observability framework.

README

OpenTelemetry Core

This package provides default implementations of the OpenTelemetry API for trace and metrics. It's intended for use both on the server and in the browser.

Built-in Implementations

• Built-in Propagators
  • HttpTraceContext Propagator
  • B3 Propagator
  • Composite Propagator
  • Correlation Context Propagator
• Built-in Sampler
  • Always Sampler
  • Never Sampler
  • Probability Sampler

Built-in Propagators

HttpTraceContext Propagator

OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.

This is used as a default Propagator

const api = require("@opentelemetry/api");
const { HttpTraceContext } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new HttpTraceContext());

B3 Propagator

This is propagator for the B3 HTTP header format, which sends a SpanContext on the wire in an HTTP request, allowing other services to create spans with the right context. Based on: https://github.com/openzipkin/b3-propagation

const api = require("@opentelemetry/api");
const { B3Propagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new B3Propagator());

Composite Propagator

Combines multiple propagators into a single propagator.

const api = require("@opentelemetry/api");
const { CompositePropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new CompositePropagator());

Correlation Context Propagator

Provides a text-based approach to propagate correlation context to remote services using the OpenTelemetry CorrelationContext Propagation HTTP headers.

const api = require("@opentelemetry/api");
const { HttpCorrelationContext } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new HttpCorrelationContext());

Built-in Sampler

Sampler is used to make decisions on Span sampling.

Always Sampler

Samples every trace regardless of upstream sampling decisions.

This is used as a default Sampler

const { NodeTracerProvider } = require("@opentelemetry/node");
const { ALWAYS_SAMPLER } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: ALWAYS_SAMPLER
});

Never Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const { NodeTracerProvider } = require("@opentelemetry/node");
const { NEVER_SAMPLER } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: NEVER_SAMPLER
});

Probability Sampler

Samples a configurable percentage of traces, and additionally samples any trace that was sampled upstream.

const { NodeTracerProvider } = require("@opentelemetry/node");
const { ProbabilitySampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: new ProbabilitySampler(0.5)
});

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us on gitter

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.8.3

:rocket: (Enhancement)

• opentelemetry-node
  • #980 feat: merge user supplied and default plugin configs (@naseemkullah)

:bug: (Bug Fix)

• opentelemetry-context-async-hooks
  • #1099 fix(asynchooks-scope): fix context loss using .with() #1101 (@vmarchaud)

:books: (Refine Doc)

• Other
  • #1100 docs(batcher): document how to configure custom aggregators #989 (@vmarchaud)
• opentelemetry-api
  • #1106 chore: improve API documentation (@mayurkale22)

Committers: 7

• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Kanika Shah (@kanikashah90)
• Mayur Kale (@mayurkale22)
• Naseem (@naseemkullah)
• Valentin Marchaud (@vmarchaud)
• @shivkanya9146